Grammar inconsistency in box-shadow syntax example: | vs. &&

[kannanwisen]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow

What specific section or headline is this issue about?

Syntax CSS

What information was incorrect, unhelpful, or incomplete?

I've noticed a recurring issue with the syntax notation in example comments across MDN Web Docs pages. This often leads to confusion when trying to interpret the required components of CSS properties based on formal grammar.

For example, on the box-shadow page:
URL: https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow

Under the "Syntax" section, an example comment provides:

CSS

/* A color and two length values */
/* <color> | <length> | <length> */
box-shadow: red 60px -16px;

The Problem:

In this specific example, the box-shadow property must contain a color and two length values (at minimum, for offset-x and offset-y). However, the comment uses the pipe symbol |.

According to standard BNF (Backus-Naur Form) grammar and even within the specific CSS Value Definition Syntax, the | symbol denotes an "OR" relationship, meaning one choice out of several options. This directly contradicts the requirement for these components to be combined (AND), not chosen exclusively (OR).

What did you expect to see?

Suggestion for Improvement:

To accurately represent that these components are all required as part of the combined value, the syntax comment should use && (double ampersand), which in CSS Value Definition Syntax signifies that 'all components must be present, and their order is arbitrary.'

Therefore, I suggest the syntax comment be rewritten as follows:

CSS

/* <color> && <length> && <length> */

This correction would greatly improve clarity and align the example comments more closely with formal CSS grammar principles, reducing potential confusion for developers.

Do you have any supporting links, references, or citations?

In all MDN Web Docs where Syntax CSS available

Do you have anything more you want to share?

No response

[Josh-Cena]

You are correct that the comment here is definitely wrong. Please let us know if you find any other cases like this.

[kannanwisen]

In almost all the pages which contain a Syntax section.

[Josh-Cena]

Yeah, it appears that this is a convention :/ We need to see if it's intended.

[Psychpsyo]

Note that the spec does not require the <color> in this case, only the two <length>s
The spec grammar is none | <shadow>#, and <shadow> = <color>? && [<length>{2} <length [0,∞]>? <length>?] && inset?.
The ? in <color>? makes it optional.

[kannanwisen]

@Psychpsyo Here the problem is in grammar in all the pages which contain a Syntax section.

[kannanwisen]

Yeah, it appears that this is a convention :/ We need to see if it's intended.

Even if intentional, the grammar is really confusing with respect to w3.org grammar.

[dipikabh]

Thanks for reporting this, @kannanwisen.

1. On https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow#syntax, the comment:

/* <color> | <length> | <length> */

is incorrect; it doesn't reflect the intended syntax. What should suffice is the prose-style comment before it, that is:

/* A color and two length values */

We should get rid of all these comments:

/* <color> | <length> | <length> */
/* <length> | <length> | <length> | <color> */
/* <length> | <length> | <length> | <length> | <color> */
/* <inset> | <length> | <length> | <color> */

2. I noticed a similar issue on https://developer.mozilla.org/en-US/docs/Web/CSS/text-shadow#syntax. These comments can be replaced with plain prose.

In almost all the pages which contain a Syntax section.

Can you link a few other pages where you see this issue? Thanks!

Would you be willing to open a PR to send a fix?

[kannanwisen]

@dipikabh

I am not able to recall right now. Surely, I will check and inform.

I will open the PR soon.

[Josh-Cena]

For example https://developer.mozilla.org/en-US/docs/Web/CSS/margin also has this problem

[kannanwisen]

If there is an issue with margin, then padding and border will likely have a similar issue.